Bring the wire format and API to parity with TypeScript SDK 3.0.1 - #84

Replaces the manual `make docker-run-clean` + AGGREGATOR_URL/AGGREGATOR_TRUSTBASE
setup with a stack the suite starts itself. `npm run test:aggregator` is now the
whole instruction: cold start to green in about 1m45s, against nothing.

The compose is copied from state-transition-sdk-js
`tests/integration/docker/docker-compose.yml`, which the Java SDK mirrors as
well (unicitynetwork/state-transition-sdk-java#84). Keeping the three identical
is the point — if each repo exercised a different service build, "passes against
a real aggregator" would mean something different in each one. It pins the
prebuilt ghcr.io/unicitynetwork/aggregator-go image, so no local rocksdb build:
that alone was the ~10 minutes the manual path cost on a cold machine.

Two things the harness gets right that a naive port would not:

- It waits for consensus to CERTIFY A ROUND, not for the container to report
  healthy. Until the service has a reference time it answers every certification
  request SERVICE_NOT_READY, so a health-gated wait races startup.
- It wipes the bind-mounted genesis before AND after. Genesis survives a
  container teardown while the mongodb and redis volumes do not, so a reused
  directory pairs a chain that remembers nothing with a root node that remembers
  everything.

The suite always starts its own stack rather than accepting a URL. Pointing it
at someone else's service is what test:e2e is for, and would mean a green run
proved nothing about the compose file this suite exists to exercise.

…e) — ships as 0.15.0 (#761)

* feat!: state-transition-sdk 3.0.1 — request deadlines and reference time

v3 threads one new concept through the protocol: every transaction carries
`expiresAt`, an exclusive request deadline, and every inclusion proof carries
the `referenceTime` of the round that certified it. The sparse-Merkle leaf is
now H(transactionHash, referenceTime) rather than the bare hash, and every
wire version underneath moved — nothing 2.x wrote decodes, and nothing 2.x
writes is accepted.

Sphere sets no deadline anywhere. Not for determinism — a deadline persisted
on the durable intent would rebuild byte-identically — but because this is a
browser wallet with an untrusted clock, and because an absolute deadline is
unrecoverable across downtime longer than the window: every resume would
rebuild an already-expired transaction and the intent would sit open forever
with its sources reserved. Omitted means the service assigns one from
consensus time and does not record it.

That policy is load-bearing rather than cosmetic. `expiresAt` is committed by
the transaction hash but is NOT part of the StateId, so two attempts that
disagree about it address the same leaf with different hashes — and the
verification rule compares the hash first, so the disagreement surfaces as
TRANSACTION_HASH_MISMATCH, i.e. as a foreign spend. A clock-derived deadline
would make every crash-resume abort an intent whose spend is already on chain.
expires-at.test.ts pins it, including a 24-hour clock jump between attempts.

REQUEST_EXPIRED and SERVICE_NOT_READY stay out of CLEAN_REJECT_STATUSES
despite their names: each reports only that THIS submit was not admitted,
never that no earlier attempt certified. SERVICE_NOT_READY is instead retried
at the submit call site — it is a 503 in a 200 body, and left alone it
surfaced CERTIFICATION_UNCONFIRMED for a booting gateway.

3.0.1 also reshaped the proof types: `InclusionProofResponse.inclusionProof`
is now nullable and null IS "not certified yet", so `isSpent` and the split
pre-flight read the response instead of digging for certification data.

Closes #760

* test: probe the two invariants the 3.x migration introduced

The deadline policy and the KV generation rename are both money-critical and
both invisible in a type signature, so they get probes rather than only tests.

`engine-sets-clock-derived-deadline` reproduces the failure the policy exists
to prevent: a deadline read off the wall clock makes a crash-resumed rebuild
address the same leaf with a different transaction hash, which the rule reports
as TRANSACTION_HASH_MISMATCH and the engine maps to TransferConflictError — so
the wallet aborts an intent whose spend is already on chain, demotes the
source, and re-sends the amount from other sources.

`kv-generation-not-renamed` puts the prefix back on `pv2:`, which is enough for
a surviving sync-epoch latch to make a backend reset look like a server restore
and re-PUT dead intents into the fresh backend.

Also re-anchors submit-429-not-retried, whose find text moved with the
SERVICE_NOT_READY retry, and corrects three comments that still named the old
`pv2:` prefix or the removed paymentsV2 alias.

* docs: document the 3.x flag day, and correct what the bump exposed

Rewrites CLAUDE.md, the changelog, the design docs and the consumer docs for
the state-transition-sdk 3.0.1 migration: what v3 is, why sphere sets no
request deadline, why the two new time-dependent statuses are not clean
rejects, the TokenBlob removal, the split-checkpoint version bump, the scoped-KV
generation rename, and the removal of the paymentsV2 alias — including the
behavioural difference consumers will otherwise meet in production, that
`sphere.payments` throws where the alias returned null.

Several corrections are to statements that were already false before this
branch, found while verifying the ones being written:

- The canonical Quick Start would have thrown INVALID_CONFIG. `Sphere.init`
  resolves the payments composition from its OWN `network` and compares it to
  `walletApi.network` as a string, but the example passed `network` only to
  createBrowserProviders (where it lands inside the oracle argument, not at
  bundle top level) and used the 'testnet' alias against 'testnet2'. README
  called `network` on Sphere.init "optional/informational"; it is required and
  all three must agree.
- `history:updated` was documented as an empty payload in three files. It has
  carried a HistoryEntry since c4fb918.
- docs/PAYMENTS-V2-DESIGN.md §5.5 justified never retrying REQUEST_EXPIRED with
  "a re-submit is a different transaction hash" — false here precisely because
  sphere sets no deadline, so the rebuild is byte-identical. The real reason is
  that reference time only advances.
- docs/MIGRATION-PAYMENTS-V2.md §5's mixed-version compatibility matrix claimed
  interop that no longer exists in either direction.
- LEGACY-INVENTORY records the 3.x removals. Those entries were correctly
  refuted as unremovable when written; the bump changed the facts, not the
  reasoning, and the pass-through arm the refutation rested on survives as the
  plain Token.fromCBOR in deriveDeliveryKeys.

* docs: cut the padding this bump did not need

The docs pass ran wide and over-wrote. Removed, without losing a fact:

- The README release-note section. It duplicated the changelog, went stale on
  the next release, and introduced a section convention this repo does not have.
  The paymentsV2 migration guidance stays but is a third of its length; the
  deeper version lives in INTEGRATION.md, which is where an upgrader looks.
- The expiresAt rationale had four copies. It now has two — CLAUDE.md, because
  that file is the standing context, and the CHANGELOG, because that is the
  release record. INTEGRATION.md points at them instead of restating.
- CLAUDE.md's enumeration of the changed SDK signatures. Exact shapes are in the
  types; the file needs the POLICY, not a second copy of the changelog.
- CONNECT.md repeated "getBalance and getAssets are the same call" three times.
- The changelog's API paragraph and host-shape section, tightened.

Kept deliberately: docs/VERIFICATION-WORKERS.md grew because the entry script it
documents was broken before this branch — the worker base has required two
verifiers since 2.1.0, so the published script did not compile. PAYMENTS-V2-DESIGN
and MIGRATION-PAYMENTS-V2 grew because they carried false statements about
determinism inputs and cross-version interop.

Docs diff: 1050 added -> 928.

* chore: release v0.15.0-dev.1

* fix(connect): keep compat events alive while the facade is torn down

Codex P2 on #761, and it is a regression this branch introduced.

`stopPaymentsV2Inner` clears `_paymentsV2Active` BEFORE awaiting
`PaymentsFacade.stop()` (core/Sphere.ts) — deliberately, so no new operation
can start against a stopping facade. But stop() is exactly where in-flight ops
settle and emit, so a `payment_request:updated` can arrive while the public
`sphere.payments` getter throws NOT_INITIALIZED.

Sphere's `emitEvent` catches a throwing handler and only logs it. So the compat
adapter's unguarded read did not surface an error to anyone — the dApp simply
never received the terminal paid/rejected/expired event. The `sphere.paymentsV2`
alias this replaced was optional-chained, so the same window produced the
degraded id + status payload instead. That is the null-vs-throws difference the
release notes warn consumers about, reintroduced inside our own call sites.

`paymentsOrNull()` restores the previous semantics at the two EVENT call sites.
The query-router reads stay unguarded on purpose: a throw there becomes a typed
ConnectError the dApp can see and retry, which the lock suite already pins.

Two tests, both failing before the fix.

* test: prove the wire against a real aggregator-go v3, not just against ourselves

Every other suite that exercises the chain runs on TestAggregatorClient, which
orchestrates the SDK's own SMT, CertificationData and verification rule. That
proves this client is self-consistent; it cannot prove the client and the
SERVICE agree, because both sides were built from the same written spec and a
spec can be read two ways. The integration suites prove less about the wire
still — they swap a fake engine in through setEngine, so they pin facade
orchestration and would pass with the CBOR wrong.

That was the gap worth closing before a flag day with no straddle window, and
it does not need testnet: aggregator-go ships a compose that stands up a real
root + aggregator locally and generates its own trust base.

tests/aggregator/ runs the real engine against it — mint, transfer with the
RECIPIENT's own engine verifying, split with value conserved, and a
same-transferId re-call recovering the byte-identical token. That last one is
E.1 determinism against a real service, which is exactly what the no-deadline
policy protects.

`verify()` passing is the assertion no fake can make: the leaf this client
computes — H(transactionHash, referenceTime) since 3.x, where 2.x used the bare
hash — reproduces the leaf the Go service actually inserted, and the BFT
certificate chains to the service's own trust base. Checked it is not vacuous:
a well-formed but wrong root key fails INVALID_TRUSTBASE.

Opt-in via AGGREGATOR_URL + AGGREGATOR_TRUSTBASE, like test:relay — skipped, not
failed, when unset, so test:run is untouched.

* test(aggregator): stand the stack up with Testcontainers, not by hand

Replaces the manual `make docker-run-clean` + AGGREGATOR_URL/AGGREGATOR_TRUSTBASE
setup with a stack the suite starts itself. `npm run test:aggregator` is now the
whole instruction: cold start to green in about 1m45s, against nothing.

The compose is copied from state-transition-sdk-js
`tests/integration/docker/docker-compose.yml`, which the Java SDK mirrors as
well (unicitynetwork/state-transition-sdk-java#84). Keeping the three identical
is the point — if each repo exercised a different service build, "passes against
a real aggregator" would mean something different in each one. It pins the
prebuilt ghcr.io/unicitynetwork/aggregator-go image, so no local rocksdb build:
that alone was the ~10 minutes the manual path cost on a cold machine.

Two things the harness gets right that a naive port would not:

- It waits for consensus to CERTIFY A ROUND, not for the container to report
  healthy. Until the service has a reference time it answers every certification
  request SERVICE_NOT_READY, so a health-gated wait races startup.
- It wipes the bind-mounted genesis before AND after. Genesis survives a
  container teardown while the mongodb and redis volumes do not, so a reused
  directory pairs a chain that remembers nothing with a root node that remembers
  everything.

The suite always starts its own stack rather than accepting a URL. Pointing it
at someone else's service is what test:e2e is for, and would mean a green run
proved nothing about the compose file this suite exists to exercise.

* fix(test): keep the docker-backed aggregator suite out of test:run

The default vitest config globs tests/**, and dropping the env gate meant the
Testcontainers suite ran inside `npm run test:run` — quietly making the default
suite require Docker and adding ~2 minutes to it. Excluded alongside e2e and
relay, which are out for the same reason.

Caught by the file count: 117 -> 118.

---------

Co-authored-by: github-actions[bot] <github-actions[bot]@users.noreply.github.com>